XML2CSV
=======

Экспорт данных и структуры из файлов XML в файлы формата CSV.

Исполняемые модули: <https://gitverse.ru/panarinv/index/content/master/programs/xml2csv>.  
Исходный код: <https://gitverse.ru/panarinv/xml2csv>.


ВОЗМОЖНОСТИ
-----------

Программа отображает данные из файлов XML в виде набора файлов формата CSV.
Данное преобразование упрощает загрузку и обработку данных реляционными СУБД.

Особенности работы:

* Для каждого типа элемента XML создаётся отдельный CSV-файл.
* Значения атрибутов и элементов размещаются в одноимённых полях CSV-файла.
* Иерархия элементов отображается в именах и полях (*_id) файлов данных.
* Имена элементов и атрибутов набранные кириллицей транслитерируются латиницей.
* Можно задать правила переименования элементов и атрибутов (см. описание).
* Получаемые файлы данных могут быть сжаты GZIP (см. параметр "z").
* Если задано несколько XML файлов, то CSV размещаются в отдельных каталогах.

Программа НЕ предназначена:

* для проверки структуры файлов XML или их соответствия XSD-схеме
  (проверяется только базовые требования формата XML);
* для преобразования структуры XML или выборочного извлечения отдельных значений
  (для данных целей лучше подойдёт технология XSLT);
* для дословного отображения элементов, атрибутов и значений из файлов XML
  (значения очищаются и преобразуются, схемы игнорируются см. описание);
* для обработки файлов, размер которых превышает доступную оперативную память
  (большие файлы следует разделять и обрабатывать порциями приемлемого размера).


ТРЕБОВАНИЯ
----------

Установка не требуется, достаточно скопировать исполняемый файл для нужной ОС.
От пользователей требуется знания и навыки работы с форматами XML и CSV.


ИСПОЛЬЗОВАНИЕ
-------------

Программа использует текстовый (консольный) интерфейс.
Для запуска введите команду:

    xml2csv [параметры] XML-файлы...
    
    Параметры:
      -d <символ> - разделитель полей в файлах данных (по умолчанию TAB);
      -o <путь>   - путь к каталогу вывода данных (по умолчанию "OUT");
      -t <файл>   - файл со словарём для замены (по умолчанию "translate.txt");
      -z          - сжимать получаемые файлы GZIP (расширение ".csv.gz");
      -m <число>  - количество потоков обработки XML-файлов (по умолчанию "2").

В процессе работы программа выводит на консоль список обрабатываемых файлов.

В ОС Windows можно просто перетащить файл XML на файл программы.


ПРИМЕР
------

Исходный XML:

    <root>
      <element attr1="100" attr2="value1"/>
      <element attr1="200">Text_1</element>
      <element attr1="300" attr2="value2">
        Текст   2
        Текст   3
      </element>
    </root>

Получаемые файлы данных:

    root:
      root_id
      1

    root__element:
      root_id  element_id  attr1  attr2   element
      1        1           100    VALUE1
      1        2           200            TEXT_1
      1        3           300    VALUE2  ТЕКСТ 2 ТЕКСТ 3


ОПИСАНИЕ
--------

### Правила обработки файлов XML

Для каждого типа элемента XML создаётся отдельный CSV-файл.
Значения из атрибутов и элементов размещаются в полях файла данных.

Структура (вложенность) XML-элементов отображается в именах файлов данных
 и полях идентификаторов, называемых "<имя-элемента>_id".
Поля идентификаторов содержат порядковые номера элементов в структуре XML.
В каждом файле представлены поля идентификаторов для всех элементов в иерархии.

Если задано несколько файлов XML,
 то CSV файлы размещаются в отдельных каталогах с именами исходных файлов XML,
 а поле идентификаторов первого (корневого) элемента
 содержит порядковый номер файла XML.
Порядковые номера файлов XML выводятся на консоль в процессе работы.

Если в документе XML для элементов задана схема (например "<schema:element/>"),
 то выводятся только локальные имена элементов, схемы игнорируются.

### Преобразование имён элементов и атрибутов

Для имён элементов и атрибутов выполняются следующие преобразования:

* Имена элементов и атрибутов приводятся к строчному регистру.
* Имена могут заменятся по словарю из файла (по умолчанию "translate.txt",
   формат записи словаря: "имя-в-XML-документе[разделитель]имя-в-файле-данных",
   где разделитель - любые пробельные символы).
* Имена, набранные кириллицей, транслитерируются латиницей.

### Модификация значений элементов и атрибутов

Для значений элементов и атрибутов выполняются следующие преобразования:

* Текстовые значения атрибутов и элементов приводятся к заглавному регистру.
* Из значений атрибутов и элементов удаляются специальные (непечатные) символы,
  двойные и одинарные кавычки и лидирующие/завершающие пробелы,
  несколько пробелов подряд заменяются одним.
* Значения (даты) в формате "ДД.ММ.ГГГГ" преобразуются в "YYYY-MM-DD".

### Сжатие файлов XML и CSV

Получаемые файлы данных могут быть сжаты по технилогии GZIP
 (параметр "-z", расширение файлов - ".csv.gz").
Исходные файлы XML-документов могут быть сжаты GZIP (расширение ".xml.gz").

### Расход оперативной памяти

В процессе работы все данные из всех переданных файлов XML
 содержатся в оперативной памяти, что может замедлить обработку больших файлов
 на компьютерах с недостаточным количеством свободной оперативной памяти.
Файл XML прочитывается и обрабатывается целиком, т.к. по начальным фрагментам
 невозможно составить точную структуру создаваемых CSV файлов.
Рекомендуется разделять и обрабатывать файлы XML порциями приемлемого размера.


ЛИЦЕНЗИЯ
--------

Это свободное программное обеспечение.
Вы можете повторно распространять или изменять его
 в соответствии с условиями лицензии BSD.
Полный текст лицензии в файле LICENSE.

`(c) 2022-2024 Вячеслав Панарин (panarinv@mail.ru)`
